
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Header:

\title{
  \textbf{{\Huge Locoseq}\\
    A Loop-based Controllable Sequencer}\\
  The Manual}
\author{Sebastien MONDET\thanks{\url{http://sebmdt.googlepages.com}}\ \and
Frederic MOULINS}

\date{\today}

\hypersetup{ 
    pdfauthor   = {Sebastien MONDET, Frederic MOULINS},%
    pdftitle    = {Locoseq Manual},%
    pdfsubject  = {},%
    pdfkeywords = {Midi, Ocaml, Sequencer}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Document:


\begin{document}
%\sffamily

%\onecolumn
\maketitle
\tableofcontents
%\twocolumn

\newpage

\section{Presentation}

\href{http://locoseq.googlecode.com}{Locoseq} is a midi sequencer designed for
live playing looping tracks.  You can create control tracks (called
"meta-tracks") that drive the sequencer (schedule track \textit{x}, mute,
change tempo...) and you can configure how the sequencer reacts on a given
input (midi-in port or keyboard).


The application is built on top of the \href{http://jackaudio.org/}{jack}
API, it is written in
\href{http://www.ocaml.org}{ocaml}
(except the code wrapping asoundlib) and uses GTK+ and glade
(\href {http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html}{lablgtk2})
for its GUI.

The source code is available under a classic MIT license (see
\ref{sec:copyright}).



\section{Installation And Usage}

\subsection{Requirements}

For the moment, let's talk about ubuntu packages as the project is developed
under 64studio. 

Those pakages should make you download all needed dependencies to compile the
application:

\ShellCmd{ apt-get install libjack-dev libxml-light-ocaml-dev omake
ocaml-findlib liblablgtk2-ocaml-dev }

Those packages should make you download all needed dependencies to compile the
documentation:

\ShellCmd{ apt-get install tetex-bin tetex-extra hevea }

\subsection{Build}

Just type:

\ShellCmd{omake}

\subsection{Use}

Launch the application:

\ShellCmd{./src/locoseq gui}

\subsection{Examples}
In the test directory:

\begin{verbatim}
\__ test
 |  \__ one_song.xml
 |  \__ tracks.mid
\end{verbatim}

The xml is a "whole" song (open with "Open").  The mid is a midifile containing
some tracks (import with "Import" in the midi-tracks view), it has been made
with \href{http://www.filter24.org/seq24/}{seq24}.

It's just for testing, it should render something more or less audible with a
classical General Midi setup (\textit{e.g.} some FluidSynth with a common
soundfont).

\subsection{If it does not work}

This software is still under heavy development. If you detect problems please
send an e-mail to the developers. If you can, send them also the result of the
portability inspection (\ref{sec:inspect}).


\section{Development}

\subsection{Portability Inspection}
\label{sec:inspect}

To generate some debug information for the developers simply type (you will see
many errors in the term):

\ShellCmd{omake inspection}

then, you can:

\ShellCmd{\$BROWSER InspectionData/Inspection.xhtml}

or

\ShellCmd{man InspectionData/Inspection.man}

And send the file \FileName{InspectionData/Inspection.t2t} to the developers.

\subsection{Standard Midi File Debug}
You can dump a midi file:

\ShellCmd{./src/locoseq parse <midi\_file>}

\subsection{The file util.env}
The command:

\ShellCmd{. util/util.env}

should be useful as it gives some functions:
\texttt{mk}, \texttt{cln}, \texttt{svns} (colorized \texttt{'svn stat -u'}) and
\texttt{docbro} (open ocamlbrowser with many libs).

\subsection{Development Tools}

In addition to ocaml distribution and omake:

\begin{itemize}
  \item the RAD tool used is \texttt{glade-3} (with special
  \textit{semi-compiler} \texttt{lablgladecc2})
  \item for inspection reports (\ref{sec:inspect}) we use
  \href{http://txt2tags.sourceforge.net/}{txt2tags}
  \item this documentation is built with \LaTeX2e\ and 
  \href{http://hevea.inria.fr/}{Hevea}
\end{itemize}

\subsection{Documentation}

\subsubsection{README file}

Now the README file is an inpendent text file.

\subsubsection{Manual}

To generate the manual (pdf and HTML):

\ShellCmd{omake doc}

\subsubsection{Code}

To generate in \FileName{doc/ref/html/} the code documentation, just type:

\ShellCmd{omake codedoc}


\subsection{The Source Tree}

\begin{verbatim}
\__ src                                        
 |  \__ main.ml               -> main, inspection, midi test
 |  \__ midiFile.ml           -> midi file read and write
 |  \__ tracker.ml            -> the sequencer
 |  \__ midi.ml               -> manipulation of MIDI "Data"
 |  \__ jackseq.c             -> jack-midi code
 |  \__ jackSequencer.ml      -> OCamL functions for jackseq usage
 |  \__ gui_files                   
 |   |  \__ app.glade         -> main Glade file
 |  \__ gui.ml                -> the main GUI code is there
 |  \__ guiEditor.ml          -> the code for the generic track editor
 |  \__ stringServer.ml       -> attempt to group the user messages
 |  \__ seqApp.ml             -> the "model interface", many functions for gui.ml 
 |  \__ inputManager.ml       -> event handler of the tracker and midi listener
 |  \__ log.ml                -> logging facilities
\__ OMakefile                 -> General build file
\__ OMakeroot                 -> Root for omake
\__ test                                       
 |  \__ tracks.mid  
 |  \__ one_song.xml                             
\__ doc
 |  \__ manual
 |   |  \__ src
 |   |   |  \__ latex-header.tex
 |   |   |  \__ latex-main.tex
 |   |   |  \__ manual.tex
 |   |   |  \__ OMakefile
 |   |  \__ locoseq-doc.pdf
 |   |  \__ locoseq-doc.html
\__ util                      
 |  \__ util.env              -> utilities for development
\__ licence.mit               -> licence template
\__ README                    -> README file
\end{verbatim}


\section{Copyright}
\label{sec:copyright}

This software is released under an MIT licence:

\begin{verbatim}
Copyright (c) 2007, Sebastien MONDET

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
\end{verbatim}
Current contributors are:

\begin{itemize}
\item \href{http://sebmdt.googlepages.com}{Sebastien MONDET}
\item Frederic MOULINS
\end{itemize}


\end{document}

